The process of choosing which files, folders, and volumes to display in the browser list or the pop-up menus is known as object filtering. If your application needs simple, straightforward object filtering, pass a pointer to a structure of type to the appropriate Navigation Services function. If you desire more specific filtering, Navigation Services lets you implement an application-defined filter function. Filter functions give you more control over what can and can't be displayed; for example, your function can filter out non-HFS objects. You can use both a structure and a filter function if you wish, but keep in mind that your filter function is directly affected by the structure. For example, if the structure contains only


'TEXT'

and


'PICT'

types, only files of those types are passed into your filter function. Also, your filter function can filter out file types that are defined in your structure. Make sure you don't accidentally exclude items you wish to display by creating conflicts between your type list and filter function.

Navigation Services tells you which dialog box control was used for each call to your filter function, so you can implement different criteria for each control. You might choose to limit the Desktop button to displaying specific volumes, for example, or to restrict navigation through the Location pop-up menu. The default location and selections can also be filtered. For more information on implementing a filter function, see Providing Custom Object Filtering.

The function displays a Show pop-up menu that lists your application's native types as well as translatable file types. If the user chooses a translatable file type, Navigation Services ignores your structure and responds only to your filter function. For more information on the Show pop-up menu, see Providing File Opening Options.

The function displays a Format pop-up menu that displays the save format options, the application's native types, and the file types that can translated. This pop-up menu selection does not affect filtering of the browser list; it determines the file format used to save the final document.

Object Filtering Scenarios

This section gives some examples to help explain how filtering works in the Show pop-up menu. For purposes of illustration, assume the following:

The application Sampler can open files of type '


TEXT

' and '


PICT

Sampler passes to the function a structure of type that contains these two file types as well as Sampler's application signature.

Sampler implements a kind string for each of these native file types.

Sampler specifies the


kNavDontAddTranslateItems

constant in the


dialogOptions

field in the structure of type that it passes in the


dialogOptions

parameter of the function.

The Show pop-up menu contains the items shown in Figure 2-14. Note that the menu does not contain a translatable file section.

Figure 2-14 A Show pop-up menu without a translatable file section

The user can select the All Readable Documents command to display all of Sampler's native file types at once.

If Sampler specifies the kNavNoTypePopup constant in the dialogOptions field, no Show pop-up menu appears and Sampler's structure and filter function determine any filtering. If Sampler passes NULL to the function in place of a reference to the structure, the Show pop-up menu does not appear (regardless of the dialog options) and Sampler's application-defined filter function is the only determining filter. If Sampler doesn't provide a filter function, all files are displayed.

Note: Under Navigation Services 1.1 or later, if your application passes a structure to the function and specifies the kNavNoTypePopup constant, Navigation Services displays all files of the types described in the structure, even if they were created by a different application.

In the next example, assume the following:

The application Portal can open files of type '


TEXT

', '


PICT

', and '


MooV

Portal has a structure of type containing these three file types as well as its application signature.

Portal provides kind strings for each of these native file types.

Portal supplies the


kNavAllFilesInPopup

constant in the


dialogOptions

field of the structure. This adds the All Documents item at the bottom of the menu.

Portal does not supply the


kNavDontAddTranslateItems

constant in the


dialogOptions

field of the structure.

In this case, the Show pop-up menu appears as shown in Figure 2-15.

Figure 2-15 A Show pop-up menu with a translatable files section

The third section of the Show menu shows file types that the Translation Manager can translate into one of Portal's three native file types.

Under Navigation Services 1.1 or later, if the user chooses the All Readable Documents menu item, Navigation Services displays all native and translatable file types, regardless of which application created them. If the user chooses the All Documents menu item, the browser list shows all file types, regardless of whether Portal has identified them as translatable or not.

Refreshing the Browser List

If your application needs to refresh the list of file objects in the browser before exiting a function such as , follow these steps if you are using a version of Navigation Services earlier than 2.0:

Supply the kNavCtlGetLocation constant in the selector parameter of the function to obtain the current location.
Pass the current location in the parms parameter of NavCustomControl and supply the kNavCtlSetLocation constant in the selector parameter of NavCustomControl .

Getting and setting the current location causes Navigation Services to rebuild the browser list. For more information on these constants, see .

Navigation Services 2.0 and later provides the constant that you can specify in the the selector parameter of the function to force the browser list to be refreshed.

Filtering File Objects

Object Filtering Scenarios

Figure 2-14 A Show pop-up menu without a translatable file section

Figure 2-15 A Show pop-up menu with a translatable files section

Refreshing the Browser List